/**
 * Copyright 2006 gworks.com.au
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License. (http://www.apache.org/licenses/LICENSE-2.0)
 *
 * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed 
 * on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for 
 * the specific language governing permissions and limitations under the License.
 *
 * <dhamma-message src="Atisha (11th century Tibetan Buddhist master)">
 * 	The greatest achievement is selflessness. The greatest worth is self-mastery.
 * 	The greatest quality is seeking to serve others. The greatest precept is continual awareness.
 * 	The greatest medicine is the emptiness of everything. The greatest action is not conforming with the worlds ways.
 * 	The greatest magic is transmuting the passions. The greatest generosity is non-attachment.
 * 	The greatest goodness is a peaceful mind. The greatest patience is humility.
 * 	The greatest effort is not concerned with results. The greatest meditation is a mind that lets go.
 * 	The greatest wisdom is seeing through appearances. 
 * </dhamma-message>
 */
package org.javaongems.client.forms;

/**
 * <p>Provide a specification for subscribing to events that occur on a form.</p>
 * <p>Responsibilities:
 * <ul>
 * 	<li> support form show, hide and refresh invocations
 *  <li> support form close request invocations
 *  <li> support minimise, maximise, resize & move invocations
 *  <li> support open and close invocations
 * </ul>
 * </p>
 * <p>Influences:
 * <ul>
 * 	<li> Borland Delphi's form component in the VCL
 * </ul>
 * </p>
 * 
 * @author Ashin Wimalajeewa (ash)
 */
public interface FormActionListener {
	/**
	 * invoked when the form is requested to be shown either via the setVisible() 
	 * method or the show() method.
	 */
	public void onFormShow();

	/**
	 * invoked when the form is requested to be hidden either via the setVisible() 
	 * method or the hide() method.
	 */
	public void onFormHide();
	
	/**
	 * invoked when the form is requested to be refreshed via the refresh() 
	 * method. This should typically be used to after an update to the latest 
	 * model in the controller.
	 */
	public void onFormRefresh();
	
	/**
	 * invoked prior to the form being closed
	 * 
	 * @return null - if its ok to close this form
	 * 		   String msg - veto the closure with msg and return to
	 *         the previous state
	 */
	public String onFormCloseRequest();

	/**
	 * invoked prior to minising the form from the browser client area
	 * 
	 * @return true - if its ok to minimise this form false - if the
	 *         form should not be minimised yet and return to the previous
	 *         state
	 */
	public boolean onFormMinimise();

	/**
	 * invoked prior to maximising the form from the browser client area
	 * 
	 * @return true - if its ok to maxmise this form false - if the form
	 *         should not be maximised yet and return to the previous state
	 */
	public boolean onFormMaximise();

	/**
	 * invoked when open() is called which is just before the form is shown
	 * for the first time, unless directly invoked earlier.
	 */
	public void onFormOpened();
	
	/**
	 * invoked when close() is called
	 */
	public void onFormClosed();
	
	/**
	 * invoked after the form has been moved
	 */
	public void onFormMoved();

	/**
	 * invoked after the form has been resized
	 */
	public void onFormResized();
}